Summary

Adds conditional dotenv overlays under CODEX_HOME. After loading the current .env, Codex discovers .env.* files in lexicographic order and applies each overlay when its TCP condition passes.

Evaluation and environment mutation occur during single-threaded startup, before Codex creates its runtime, workers, sessions, or network clients.

Supported behavior

• TCP connectivity checks using either:
  • Explicit host and port.
  • A URL or authority stored in an overlay assignment referenced by from.
• Direct negation of a TCP check using not.
• Setting dotenv assignments when a condition passes.
• Unsetting variables with # codex-env-unset.
• A default 500 ms connection timeout with a maximum of 5 seconds.
• Ignores filenames ending in ~ or a case-insensitive final suffix of bak, back, backup, bkp, old, orig, original, save, saved, disable, disabled, inactive, off, tmp, temp, swp, swo, example, sample, template, or dist.
• Fail-closed handling of malformed overlays without exposing environment values.
• Case-insensitive protection against setting or unsetting CODEX_* variables.

Files without a # codex-env-if: directive as their first non-empty line are ignored.

Usage

Set variables when an endpoint is reachable:

# ~/.codex/.env.10-proxy-on
# codex-env-if: {"type":"tcp_connect","from":"HTTPS_PROXY","timeout_ms":500}

HTTPS_PROXY=http://proxy.example.com:8080
HTTP_PROXY=http://proxy.example.com:8080
ALL_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1,.example.com

Unset variables when the endpoint is unreachable:

# ~/.codex/.env.20-proxy-off
# codex-env-if: {"not":{"type":"tcp_connect","host":"proxy.example.com","port":8080,"timeout_ms":500}}
# codex-env-unset: ["HTTPS_PROXY","HTTP_PROXY","ALL_PROXY","NO_PROXY"]

Each overlay is evaluated independently. A full Codex restart is required after changing overlays or moving between networks.

The timeout bounds TCP connection attempts but does not bound synchronous DNS resolution.

Testing

just test -p codex-arg0

For manual validation:

1. Configure an overlay with a reachable TCP endpoint and a test assignment.
2. Start Codex and verify the assignment is present in a spawned command.
3. Restart Codex with the endpoint unreachable and verify a negated overlay removes inherited variables.
4. Verify malformed overlays are skipped and CODEX_* variables remain unchanged.

Future ideas:

• File-existence conditions.
• Environment-variable equality conditions.
• Operating-system conditions.
• General condition composition with all, any, and arbitrarily nested not.